Server Watch Plugin SDK Date: 6 Feb 2004
Release: 1.0
Main Page | Class Hierarchy | Class List | File List | Class Members | File Members | Related Pages

ISWServerSettings Class Reference

#include <ISWServerSettings.h>

List of all members.


Detailed Description

Provides the API for retrieving server settings from Server Watch. Server Watch generates an instance of this class for each server automatically. The class is then passed into the plugin as part of the SWPluginServerStruct.

Server Watch will generate an instance of this class automatically. You will not need to store instances of this class as the appropriate instance will be passed into the plugin as a member of an SWPluginServerStruct when the plugin is expected to handle a server specific event.

Thread safety design:
This class is used in a highly threaded environment, therefore it is important that users of this class use the concurrency functions of this class correctly. You can read more about the concurrency design in the "Concurrency" section below. If these functions are not used correctly, your plugin will not work as you expect. The concurrency design of this class differs in important ways from ISWServerData, so you should understand both.


Public Types

enum  JOIN_PARAM_TYPE { ANY_TEXT, PASSWORD, BOOLEAN }

Public Member Functions

Concurrency
Functions that manage the reader/writer thread safety process

This class is used in a highly threaded environment. These functions provide an interface that, when used correctly, will protect the integrity of this class and the stability of Server Watch.

The concurrency design of this class follows a traditional readers/writers pattern, and therefore differs from ISWServerData which has significantly stricter performance restrictions.

Read Mode:

To retrieve data from an instance of the class, it must be in read mode. To accomplish this, you must first call BeginRead(). After this call, you may call any of the data retrieval functions (GetPort(), etc). Because readsers don't modify anything in the class, you can have any number of reader threads operating between BeginRead() and EndRead() calls. When you are done reading, a call to EndRead() tells the class that you are done reading and that any waiting writers can now take over and get the chance to modify the class (but only if there are no other readers active).

  // Standard usage
  pMySWServerSettings->BeginRead();
  ... Call "get" functions
  pMySWServerSettings->EndRead();

  // Deadlock Scenario
  pMySWServerSettings->BeginRead();
  pMySWServerSettings->BeginWrite(); // Deadlocks
  pMySWServerSettings->EndRead();    // You will never get here
  pMySWServerSettings->EndWrite();

  // If each is on its own thread, the above is safe. One thread will
  // wait for the other

    // Thread 1
    pMySWServerSettings->BeginRead();
    pMySWServerSettings->EndRead();
    
    // Thread 2
    pMySWServerSettings->BeginWrite();
    pMySWServerSettings->EndWrite();

  // Demonstrates how more than one can read at a time
  pMySWServerSettings->BeginRead();
  pMySWServerSettings->BeginRead(); // No Deadlock
  pMySWServerSettings->EndRead();
  pMySWServerSettings->EndRead();

Write Mode:

To write data to an instance of the class, it must be in write mode. To accomplish this, you must first call BeginWrite(). After this call, you may call any of the data setting functions (SetPort(), etc). Only one class can write at a time, and readers will also have to wait until the writer makes a call to EndWrite(). When you are done writing, a call to EndWrite() tells the class that you are done writing and that any waiting readers or writers can now take over and get the chance to run.

  // Standard usage
  pMySWServerSettings->BeginWrite();
  ... Call "set" functions
  pMySWServerSettings->EndWrite();

  // Deadlock Scenario
  pMySWServerSettings->BeginRead();
  pMySWServerSettings->BeginWrite(); // Deadlocks
  pMySWServerSettings->EndRead();    // You will never get here
  pMySWServerSettings->EndWrite();

  // If each is on its own thread, the above is safe. One thread will
  // wait for the other

    // Thread 1
    pMySWServerSettings->BeginRead();
    pMySWServerSettings->EndRead();
    
    // Thread 2
    pMySWServerSettings->BeginWrite();
    pMySWServerSettings->EndWrite();

  // Demonstrates how only one write can exist at a time
  pMySWServerSettings->BeginWrite();
  pMySWServerSettings->BeginWrite(); // Deadlocks
  pMySWServerSettings->EndWrite();   // You will never get here
  pMySWServerSettings->EndWrite();

  // If each is on its own thread, the above is safe. One thread will
  // wait for the other

    // Thread 1
    pMySWServerSettings->BeginWrite();
    pMySWServerSettings->EndWrite();
    
    // Thread 2
    pMySWServerSettings->BeginWrite();
    pMySWServerSettings->EndWrite();

Note:
Technically, it is possible to fetch data from this class without calling BeginRead(), but doing so invalidates the data integrity guaruntess of the class and could cause the program to crash. It is not possible to write to the class without previously calling BeginWrite().


virtual void BeginRead ()=0
 Puts the class in read mode.
virtual void EndRead ()=0
 Removes the class from read mode.
virtual void BeginWrite ()=0
 Puts the class in write mode.
virtual void EndWrite ()=0
 Removes the class from write mode.
virtual void Retain ()=0
 Retains the class for use.
virtual void Release ()=0
 Removes your retain rights for the class.
Monitor Mode
virtual bool ServerIsMonitoring ()=0
 Indicates whether the server is in monitor mode or not.
Server Information
Basic information required to access a server

virtual int GetPort () const =0
 Retrieves the server's port.
virtual std::wstring GetServerAddress () const =0
 Retrieves the server's address.
virtual std::wstring GetUserSetServerName () const =0
 Retrieves the name the user has given the server.
virtual std::wstring GetServerType () const =0
 Retrieves the server type.
virtual SWHandle GetServerHandle () const =0
 Retrieves the server's handle.
virtual SWHandle GetPluginHandle () const =0
 Retrieves the handle to the server's plugin.
Timings Data
Basic network timing settings

virtual int GetTimeout () const =0
 Retrieves the timeout set for a ping.
Join Functionality
These functions allow plugins to create and manage plugin specific join parameters. By default, if a plugin supports join the "Application" and "Free Form" parameters will automatically be created. Often, plugins need more than these two.

JOIN_PARAM_TYPE

virtual SWRESULT CreateJoinParam (const int id, const std::wstring &name, const std::wstring &help, const bool required=false, JOIN_PARAM_TYPE type=ISWServerSettings::ANY_TEXT)=0
 Creates a new parameter for the user to enter data into for a join.
virtual SWRESULT CreateJoinParam (const int id, const std::wstring &name, const std::wstring &help, const std::wstring &initialValue, const bool required=false, JOIN_PARAM_TYPE type=ISWServerSettings::ANY_TEXT)=0
 Creates a new parameter for the user to enter data into for a join.
virtual SWRESULT GetJoinParamValue (const int id, std::wstring &value) const =0
 Retrieves the value for a given join param identifier.
virtual SWRESULT SetJoinParamValue (const int id, const std::wstring &value)=0
 Sets the value for a given join param identifier.
virtual SWRESULT GetJoinParamHelpText (const int id, std::wstring &help) const =0
 Retrieves the help text for a given join param identifier.
virtual SWRESULT SetJoinParamHelpText (const int id, const std::wstring &help)=0
 Sets the help text for a given join param identifier.
virtual std::wstring GetJoinApp () const =0
 The full path to the application that will be used to connect to the server.
virtual SWRESULT SetJoinApp (const std::wstring &theApp)=0
 Sets the full path to the application that will be used to connect to the server.
virtual std::wstring GetJoinParamsFreeForm () const =0
 Retrieves the parameters that were entered in the free form entry box.
virtual SWRESULT SetJoinParamsFreeForm (const std::wstring &theManualParams)=0
 Sets the parameters that are to be entered in the free form entry box.


Member Enumeration Documentation

enum ISWServerSettings::JOIN_PARAM_TYPE
 

Defines the graphical type type of the property being created. The selection will have impact on the type of interface presented and the type of values the end user can enter.

Enumeration values:
ANY_TEXT  Allows any text to be entered for the property.
PASSWORD  Allows any text to be entered for the property, but that text will be obscured in the editor
BOOLEAN  Allows only true and false selections. The values presented to the plugin will be either "TRUE" or "FALSE" in string form. The default value when created will be "FALSE." The GUI may display these values as something other than "TRUE" and "FALSE," but that is what will be in the valude when the plugin reads it.


Member Function Documentation

virtual void ISWServerSettings::BeginRead  )  [pure virtual]
 

Puts the class in read mode.

Function blocks until any existing writers are finished writing.

virtual void ISWServerSettings::EndRead  )  [pure virtual]
 

Removes the class from read mode.

virtual void ISWServerSettings::BeginWrite  )  [pure virtual]
 

Puts the class in write mode.

Function blocks until all existing readers or writers have completed.

You should update everything you intend to update before calling EndWrite(). Doing partial updates allows other threads to update the class and could potentialy cause it to contain invalid data.

If you have called BeginWrite(), you can read values you have set directly by using the standard "Get" functions. Writers set all values directly without storing them in a temporary write buffer location which allows this read to occur. This is different from the functionality in ISWServerData.

virtual void ISWServerSettings::EndWrite  )  [pure virtual]
 

Removes the class from write mode.

virtual void ISWServerSettings::Retain  )  [pure virtual]
 

Retains the class for use.

Call Retain() on the class when you spawn a thread. This will allow you to use the class without fear of it being deleted while you are using it.

If you call Retain(), you must call Release() when done with the class. If you do not match each Retain call with a call to Release(), this class will not be correctly cleaned up when Server Watch is quit. If the class is not retained it is possible that it will no longer exist when you attempt to use it.

virtual void ISWServerSettings::Release  )  [pure virtual]
 

Removes your retain rights for the class.

Only call Release() if you have called Retain(). Calling Release() too many times will result in a crash in Server Watch. So, make sure your Release() and Retain() match up one-for-one.

virtual bool ISWServerSettings::ServerIsMonitoring  )  [pure virtual]
 

Indicates whether the server is in monitor mode or not.

If a server is in monitor mode, it is updateing on a regular interval. Most alerts (email, audio, etc) are only triggered when the server is in monitor mode. Therefore, you may want to consider only trigering your plugin server specific alerts when the server is in monitor mode.

Returns:
If true, the server is monitoring, otherwise it is not.

virtual int ISWServerSettings::GetPort  )  const [pure virtual]
 

Retrieves the server's port.

Returns:
An integer defining the server port.

virtual std::wstring ISWServerSettings::GetServerAddress  )  const [pure virtual]
 

Retrieves the server's address.

Returns:
A string containing the server's address.

virtual std::wstring ISWServerSettings::GetUserSetServerName  )  const [pure virtual]
 

Retrieves the name the user has given the server.

Returns:
A string containing the user name set by the user.

virtual std::wstring ISWServerSettings::GetServerType  )  const [pure virtual]
 

Retrieves the server type.

Returns:
A string containing the name of the server type

virtual SWHandle ISWServerSettings::GetServerHandle  )  const [pure virtual]
 

Retrieves the server's handle.

Returns:
The server handle

virtual SWHandle ISWServerSettings::GetPluginHandle  )  const [pure virtual]
 

Retrieves the handle to the server's plugin.

Returns:
The plugin handle

virtual int ISWServerSettings::GetTimeout  )  const [pure virtual]
 

Retrieves the timeout set for a ping.

The timeout is in seconds.

Returns:
The ping timeout length.

virtual SWRESULT ISWServerSettings::CreateJoinParam const int  id,
const std::wstring &  name,
const std::wstring &  help,
const bool  required = false,
JOIN_PARAM_TYPE  type = ISWServerSettings::ANY_TEXT
[pure virtual]
 

Creates a new parameter for the user to enter data into for a join.

Note:
The id and name of a parameter are different. This could be use by plugins to localize the names into different languages. The ID must be greater than zero.
 #define PLAYER_NAME_PARAM 1
 #define PASSWORD_PARAM    2
 #define CHOICE_PARAM      3

 // pSetings is a pointer to an instance of ISWServerSettings

 pSetings->BeginWrite();

 // Creates a regular edit field based param with a title "Name" and help
 // text of "Set the player name." The value is optional.
 pSetings->CreateJoinParam( PLAYER_NAME_PARAM, L"Name", L"Set the player name." );

 // Creates a password edit field based (displays asterisks instead of the values
 // entered) param with a title "Password" and help text of "Set the password."
 // The field is required
 pSetings->CreateJoinParam( PLAYER_NAME_PARAM, L"Password", L"Set the password.", true, ISWServerSettings::PASSWORD );

 // Creates a boolean selection based (displays a yes/no combobox) param with a title
 // "Bool" and help text of "Pick Yes or No." The field is optional (though will
 // always contain a value since it is of a boolean type).
 pSetings->CreateJoinParam( PLAYER_NAME_PARAM, L"Password", L"Pick Yes or No.", false, ISWServerSettings::BOOLEAN );

 pSetings->EndWrite();

Parameters:
id The identifier used to retrieve information from the join param. Only use positive numbers. Negative numbers and zero are reserved for parameters defined by Server Watch.
name The name to be displayed for the join param
help The help text that will be displayed for the join param
required Whether or not the join parameter is required for joining
type The new parameters type. This type indicates how it will be displayed to the user and that values that can be set on it.
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_INVALIDARG The id has already been used or is negative. Use another id.

virtual SWRESULT ISWServerSettings::CreateJoinParam const int  id,
const std::wstring &  name,
const std::wstring &  help,
const std::wstring &  initialValue,
const bool  required = false,
JOIN_PARAM_TYPE  type = ISWServerSettings::ANY_TEXT
[pure virtual]
 

Creates a new parameter for the user to enter data into for a join.

Note:
The id and name of a parameter are different. This could be use by plugins to localize the names into different languages. The ID must be greater than zero.
Parameters:
id The identifier used to retrieve information from the join param. Only use positive numbers. Negative numbers and zero are reserved for parameters defined by Server Watch.
name The name to be displayed for the join param
help The help text that will be displayed for the join param
initialValue The initial string value of the parameter if the user has not previously modified it.
required Whether or not the join parameter is required for joining
type The new parameters type. This type indicates how it will be displayed to the user and that values that can be set on it.
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_INVALIDARG The id has already been used or is negative. Use another id.
SW_OUTOFBOUNDS The value was out of the bounds for the param type indicated.

virtual SWRESULT ISWServerSettings::GetJoinParamValue const int  id,
std::wstring &  value
const [pure virtual]
 

Retrieves the value for a given join param identifier.

Note:
Boolean fields will return either L"TRUE" or L"FALSE". Other fields can return any string value.
Parameters:
id The identifier used to retrieve information from the join param
value The variable that will be set to the value associated with the join param
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INVALIDARG The specified id is not associated to a join parameter.

virtual SWRESULT ISWServerSettings::SetJoinParamValue const int  id,
const std::wstring &  value
[pure virtual]
 

Sets the value for a given join param identifier.

Note:
Boolean fields must be either L"TRUE" or L"FALSE". Other fields can contain any string value.
Parameters:
id The identifier used to set information on the join param
value The value to be associated with the join param
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_INVALIDARG The specified id is not associated to a join parameter.
SW_OUTOFBOUNDS The value specified is not allowed for the param type.

virtual SWRESULT ISWServerSettings::GetJoinParamHelpText const int  id,
std::wstring &  help
const [pure virtual]
 

Retrieves the help text for a given join param identifier.

Parameters:
id The identifier used to retrieve information from the join param
help The variable that will be set to the help text associated with the join param
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_INVALIDARG The id has already been used. Use another id.

virtual SWRESULT ISWServerSettings::SetJoinParamHelpText const int  id,
const std::wstring &  help
[pure virtual]
 

Sets the help text for a given join param identifier.

Parameters:
id The identifier used to set information on the join param
help The help text to be associated with the join param
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_OUTOFBOUNDS The value was out of the bounds for the param type.

virtual std::wstring ISWServerSettings::GetJoinApp  )  const [pure virtual]
 

The full path to the application that will be used to connect to the server.

The join app parameter is automatically created for any plugin that supports join.

Returns:
The path of the join.

virtual SWRESULT ISWServerSettings::SetJoinApp const std::wstring &  theApp  )  [pure virtual]
 

Sets the full path to the application that will be used to connect to the server.

Parameters:
theApp The full application path.
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual std::wstring ISWServerSettings::GetJoinParamsFreeForm  )  const [pure virtual]
 

Retrieves the parameters that were entered in the free form entry box.

The free form parameter is automatically created for any plugin that supports join. This parameter allows the users to add any parameters they want to in a free format.

Returns:
A string containing the free form manual parameter data

virtual SWRESULT ISWServerSettings::SetJoinParamsFreeForm const std::wstring &  theManualParams  )  [pure virtual]
 

Sets the parameters that are to be entered in the free form entry box.

The free form parameter is automatically created for any plugin that supports join. The parameter value can be any free form string.

Parameters:
theManualParams A string containing the free form manual parameter data
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()


The documentation for this class was generated from the following file:

Copyright (c) 2003-2004, Deep Fried Software. All rights reserved.